home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.n / listbox.n < prev    next >
Text File  |  1995-07-25  |  17KB  |  330 lines
  1.  
  2.  
  3.  
  4.      lllliiiissssttttbbbbooooxxxx((((nnnn))))                   TTTTkkkk (((( ))))                    lllliiiissssttttbbbbooooxxxx((((nnnn))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           listbox - Create and manipulate listbox widgets
  12.  
  13.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.           lllliiiissssttttbbbbooooxxxx _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
  15.  
  16.      SSSSTTTTAAAANNNNDDDDAAAARRRRDDDD OOOOPPPPTTTTIIIIOOOONNNNSSSS
  17.           bbbbaaaacccckkkkggggrrrroooouuuunnnndddd      ffffoooorrrreeeeggggrrrroooouuuunnnndddd     sssseeeelllleeeeccccttttBBBBaaaacccckkkkggggrrrroooouuuunnnnddddxxxxSSSSccccrrrroooollllllllCCCCoooommmmmmmmaaaannnndddd |
  18.           bbbboooorrrrddddeeeerrrrWWWWiiiiddddtttthhhh     ffffoooonnnntttt           sssseeeelllleeeeccccttttBBBBoooorrrrddddeeeerrrrWWWWiiiiddddtttthhhhyyyySSSSccccrrrroooollllllllCCCCoooommmmmmmmaaaannnndddd|
  19.           ccccuuuurrrrssssoooorrrr          ggggeeeeoooommmmeeeettttrrrryyyy       sssseeeelllleeeeccccttttFFFFoooorrrreeeeggggrrrroooouuuunnnndddd               |
  20.           eeeexxxxppppoooorrrrttttSSSSeeeelllleeeeccccttttiiiioooonnnn rrrreeeelllliiiieeeeffff         sssseeeettttGGGGrrrriiiidddd                        |
  21.  
  22.           See the ``options'' manual entry for details on the standard
  23.           options.
  24.  
  25.      WWWWIIIIDDDDGGGGEEEETTTT----SSSSPPPPEEEECCCCIIIIFFFFIIIICCCC OOOOPPPPTTTTIIIIOOOONNNNSSSS
  26.           None.
  27.      _________________________________________________________________
  28.  
  29.  
  30.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  31.           The lllliiiissssttttbbbbooooxxxx command creates  a  new  window  (given  by  the
  32.           _p_a_t_h_N_a_m_e  argument)  and  makes  it  into  a listbox widget.
  33.           Additional options, described above, may be specified on the
  34.           command  line or in the option database to configure aspects
  35.           of the listbox such as its colors, font, text,  and  relief.
  36.           The  lllliiiissssttttbbbbooooxxxx  command returns its _p_a_t_h_N_a_m_e argument.  At the
  37.           time this command is invoked, there must not exist a  window
  38.           named _p_a_t_h_N_a_m_e, but _p_a_t_h_N_a_m_e's parent must exist.
  39.  
  40.           A listbox is a widget that displays a list of  strings,  one
  41.           per line.  When first created, a new listbox has no elements
  42.           in its list.  Elements may be added or deleted using  widget
  43.           commands described below.  In addition, one or more elements
  44.           may be  selected  as  described  below.   If  a  listbox  is  |
  45.           exporting  its  selection (see eeeexxxxppppoooorrrrttttSSSSeeeelllleeeeccccttttiiiioooonnnn option), then  |
  46.           it will observe the standard X11 protocols for handling  the
  47.           selection;  listbox selections are available as type SSSSTTTTRRRRIIIINNNNGGGG,
  48.           consisting of a Tcl list with one entry  for  each  selected
  49.           element.
  50.  
  51.           For large lists only a subset of the list elements  will  be
  52.           displayed in the listbox window at once;  commands described
  53.           below may  be  used  to  change  the  view  in  the  window.
  54.           Listboxes  allow  scrolling  in  both  directions  using the  |
  55.           standard xxxxSSSSccccrrrroooollllllllCCCCoooommmmmmmmaaaannnndddd and  yyyySSSSccccrrrroooollllllllCCCCoooommmmmmmmaaaannnndddd  options.   They
  56.           also support scanning, as described below.
  57.  
  58.  
  59.      WWWWIIIIDDDDGGGGEEEETTTT CCCCOOOOMMMMMMMMAAAANNNNDDDD
  60.  
  61.  
  62.  
  63.      PPPPaaaaggggeeee 1111                                          ((((pppprrrriiiinnnntttteeeedddd 7777////22223333////99995555))))
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      lllliiiissssttttbbbbooooxxxx((((nnnn))))                   TTTTkkkk (((( ))))                    lllliiiissssttttbbbbooooxxxx((((nnnn))))
  71.  
  72.  
  73.  
  74.           The lllliiiissssttttbbbbooooxxxx command creates a new Tcl command whose name  is
  75.           _p_a_t_h_N_a_m_e.   This  command  may  be  used  to  invoke various
  76.           operations on the widget.   It  has  the  following  general
  77.           form:
  78.  
  79.                _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  80.           _O_p_t_i_o_n and the _a_r_gs determine  the  exact  behavior  of  the
  81.           command.   The  following  commands are possible for listbox
  82.           widgets:
  83.  
  84.           _p_a_t_h_N_a_m_e ccccoooonnnnffffiiiigggguuuurrrreeee ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
  85.                Query  or  modify  the  configuration  options  of  the
  86.                widget.   If  no  _o_p_t_i_o_n  is  specified, returns a list
  87.                describing all of the available  options  for  _p_a_t_h_N_a_m_e
  88.                (see  TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo for information on the format of
  89.                this list).  If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then
  90.                the  command  returns  a  list describing the one named
  91.                option  (this   list   will   be   identical   to   the
  92.                corresponding  sublist  of  the  value  returned  if no
  93.                _o_p_t_i_o_n is specified).   If  one  or  more  _o_p_t_i_o_n-_v_a_l_u_e
  94.                pairs  are  specified,  then  the  command modifies the
  95.                given widget option(s) to have the given value(s);   in
  96.                this  case the command returns an empty string.  _O_p_t_i_o_n
  97.                may have any of the  values  accepted  by  the  lllliiiissssttttbbbbooooxxxx
  98.                command.
  99.  
  100.           _p_a_t_h_N_a_m_e ccccuuuurrrrsssseeeelllleeeeccccttttiiiioooonnnn
  101.                Returns a list containing the indices  of  all  of  the  |
  102.                elements  in  the  listbox that are currently selected.  |
  103.                If there are no elements selected in the  listbox  then  |
  104.                an empty string is returned.
  105.  
  106.           _p_a_t_h_N_a_m_e ddddeeeelllleeeetttteeee _f_i_r_s_t ?_l_a_s_t?
  107.                Delete one or more elements of the listbox.  _F_i_r_s_t  and
  108.                _l_a_s_t  give  the  integer  indices of the first and last
  109.                elements in the range to be  deleted.   If  _l_a_s_t  isn't
  110.                specified  it  defaults to _f_i_r_s_t, i.e. a single element
  111.                is deleted.  An index of 0000  corresponds  to  the  first
  112.                element  in  the  listbox.  Either _f_i_r_s_t or _l_a_s_t may be
  113.                specified as eeeennnndddd, in which case it refers to  the  last
  114.                element  of the listbox.  This command returns an empty
  115.                string
  116.  
  117.           _p_a_t_h_N_a_m_e ggggeeeetttt _i_n_d_e_x
  118.                Return the contents of the listbox element indicated by
  119.                _i_n_d_e_x.    _I_n_d_e_x  must  be  a  non-negative  integer  (0
  120.                corresponds to the first element in the listbox), or it
  121.                may  also  be  specified  as  eeeennnndddd  to indicate the last
  122.                element in the listbox.
  123.  
  124.           _p_a_t_h_N_a_m_e iiiinnnnsssseeeerrrrtttt _i_n_d_e_x ?_e_l_e_m_e_n_t _e_l_e_m_e_n_t ...?
  125.                Insert zero or more  new  elements  in  the  list  just
  126.  
  127.  
  128.      Page 2                                          (printed 7/23/95)
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.      lllliiiissssttttbbbbooooxxxx((((nnnn))))                   TTTTkkkk (((( ))))                    lllliiiissssttttbbbbooooxxxx((((nnnn))))
  136.  
  137.  
  138.  
  139.                before  the  element  given  by  _i_n_d_e_x.   If  _i_n_d_e_x  is
  140.                specified as eeeennnndddd then the new elements are added to the
  141.                end of the list.  Returns an empty string.
  142.  
  143.           _p_a_t_h_N_a_m_e nnnneeeeaaaarrrreeeesssstttt _y
  144.                Given a y-coordinate within the  listbox  window,  this
  145.                command  returns  the  index  of  the (visible) listbox
  146.                element nearest to that y-coordinate.
  147.  
  148.           _p_a_t_h_N_a_m_e ssssccccaaaannnn _o_p_t_i_o_n _a_r_g_s
  149.                This  command  is  used  to   implement   scanning   on
  150.                listboxes.  It has two forms, depending on _o_p_t_i_o_n:
  151.  
  152.                _p_a_t_h_N_a_m_e ssssccccaaaannnn mmmmaaaarrrrkkkk _x _y
  153.                     Records _x and  _y  and  the  current  view  in  the  |
  154.                     listbox  window;   used  in conjunction with later  |
  155.                     ssssccccaaaannnn ddddrrrraaaaggggttttoooo commands.  Typically this  command  is  |
  156.                     associated  with  a  mouse  button  press  in  the  |
  157.                     widget.  It returns an empty string.                |
  158.  
  159.                _p_a_t_h_N_a_m_e ssssccccaaaannnn ddddrrrraaaaggggttttoooo _x _y.                                     ||
  160.                     This command computes the difference between its _x  |
  161.                     and _y arguments and the _x and _y arguments  to  the  |
  162.                     last  ssssccccaaaannnn  mmmmaaaarrrrkkkk  command for the widget.  It then  |
  163.                     adjusts the view by 10  times  the  difference  in  |
  164.                     coordinates.  This command is typically associated
  165.                     with mouse motion events in the widget, to produce
  166.                     the  effect  of  dragging  the  list at high speed
  167.                     through the window.  The return value is an  empty
  168.                     string.
  169.  
  170.           _p_a_t_h_N_a_m_e sssseeeelllleeeecccctttt _o_p_t_i_o_n _a_r_g
  171.                This command is used to adjust the selection  within  a
  172.                listbox.   It  has  several forms, depending on _o_p_t_i_o_n.
  173.                In all of the forms the index eeeennnndddd refers  to  the  last
  174.                element in the listbox.
  175.  
  176.                _p_a_t_h_N_a_m_e sssseeeelllleeeecccctttt aaaaddddjjjjuuuusssstttt _i_n_d_e_x
  177.                     Locate the end of the  selection  nearest  to  the
  178.                     element given by _i_n_d_e_x, and adjust that end of the
  179.                     selection to be at _i_n_d_e_x (i.e  including  but  not
  180.                     going   beyond  _i_n_d_e_x).   The  other  end  of  the
  181.                     selection is made  the  anchor  point  for  future
  182.                     sssseeeelllleeeecccctttt   ttttoooo  commands.   If  the  selection  isn't
  183.                     currently in the listbox,  then  this  command  is
  184.                     identical  to  the  sssseeeelllleeeecccctttt  ffffrrrroooommmm  widget  command.
  185.                     Returns an empty string.
  186.  
  187.                _p_a_t_h_N_a_m_e sssseeeelllleeeecccctttt cccclllleeeeaaaarrrr
  188.                     If the selection is in this  listbox  then  it  is  |
  189.                     cleared so that none of the listbox's elements are  |
  190.                     selected anymore.
  191.  
  192.  
  193.  
  194.      Page 3                                          (printed 7/23/95)
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.      lllliiiissssttttbbbbooooxxxx((((nnnn))))                   TTTTkkkk (((( ))))                    lllliiiissssttttbbbbooooxxxx((((nnnn))))
  202.  
  203.  
  204.  
  205.                _p_a_t_h_N_a_m_e sssseeeelllleeeecccctttt ffffrrrroooommmm _i_n_d_e_x
  206.                     Set the selection to consist of element _i_n_d_e_x, and
  207.                     make  _i_n_d_e_x  the anchor point for future sssseeeelllleeeecccctttt ttttoooo
  208.                     widget commands.  Returns an empty string.
  209.  
  210.                _p_a_t_h_N_a_m_e sssseeeelllleeeecccctttt ttttoooo _i_n_d_e_x
  211.                     Set the selection to consist of the elements  from
  212.                     the anchor point to element _i_n_d_e_x, inclusive.  The
  213.                     anchor point is  determined  by  the  most  recent
  214.                     sssseeeelllleeeecccctttt  ffffrrrroooommmm  or  sssseeeelllleeeecccctttt  aaaaddddjjjjuuuusssstttt  command  in this
  215.                     widget.  If the selection isn't  in  this  widget,
  216.                     this command is identical to sssseeeelllleeeecccctttt ffffrrrroooommmm.  Returns
  217.                     an empty string.
  218.  
  219.           _p_a_t_h_N_a_m_e ssssiiiizzzzeeee
  220.                Returns a decimal string indicating the total number of
  221.                elements in the listbox.
  222.  
  223.           _p_a_t_h_N_a_m_e xxxxvvvviiiieeeewwww _i_n_d_e_x
  224.                Adjust the  view  in  the  listbox  so  that  character  |
  225.                position  _i_n_d_e_x  is  displayed  at the left edge of the  |
  226.                widget.  Returns an empty string.                        |
  227.  
  228.           _p_a_t_h_N_a_m_e yyyyvvvviiiieeeewwww _i_n_d_e_x                                               ||
  229.                Adjust the view in the listbox so that element _i_n_d_e_x is  |
  230.                displayed at the  top  of  the  widget.   If  _i_n_d_e_x  is  |
  231.                specified  as  eeeennnndddd it indicates the last element of the  |
  232.                listbox.  Returns an empty string.
  233.  
  234.  
  235.      DDDDEEEEFFFFAAAAUUUULLLLTTTT BBBBIIIINNNNDDDDIIIINNNNGGGGSSSS
  236.           Tk automatically creates class bindings for  listboxes  that  |
  237.           give them the following default behavior:                     |
  238.  
  239.           [1]                                                                ||
  240.                When  button  1  is pressed over a listbox, the element  |
  241.                underneath the mouse cursor is selected.  The mouse can  |
  242.                be dragged to select a range of elements.                |
  243.  
  244.           [2]                                                                ||
  245.                The  ends  of the selection can be adjusted by dragging  |
  246.                with mouse button 1 while the shift key is down;   this  |
  247.                will  adjust  the end of the selection that was nearest  |
  248.                to the mouse cursor when button 1 was pressed.           |
  249.  
  250.           [3]                                                                ||
  251.                The  view  in  the  listbox can be adjusted by dragging  |
  252.                with mouse button 2.                                     |
  253.  
  254.           The behavior of listboxes can be  changed  by  defining  new  |
  255.           bindings  for  individual widgets or by redefining the class  |
  256.           bindings.  In addition, the procedure ttttkkkk____lllliiiissssttttbbbbooooxxxxSSSSiiiinnnngggglllleeeeSSSSeeeelllleeeecccctttt  |
  257.  
  258.  
  259.  
  260.      Page 4                                          (printed 7/23/95)
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.      lllliiiissssttttbbbbooooxxxx((((nnnn))))                   TTTTkkkk (((( ))))                    lllliiiissssttttbbbbooooxxxx((((nnnn))))
  268.  
  269.  
  270.  
  271.           may  be  invoked  to  change listbox behavior so that only a  |
  272.           single element may be selected at once.
  273.  
  274.  
  275.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  276.           listbox, widget
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.      Page 5                                          (printed 7/23/95)
  327.  
  328.  
  329.  
  330.